GNU Readline Library

by Brian Fox

Version 1.0

February 1989

Copyright © 1989 Free Software Foundation, Inc.

This document describes the GNU Readline Library, a utility for aiding in the consistency of user interface across discrete programs that need to provide a command line interface.

Published by the Free Software Foundation
675 Massachusetts Avenue,
Cambridge, MA 02139 USA

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

1 GNU Readline Library

2 Readline Programmer’s Manual

This manual describes the interface between the GNU Readline Library and user programs. If you are a programmer, and you wish to include the features found in GNU Readline in your own programs, such as completion, line editing, and interactive history manipulation, this documentation is for you.

2.1 Default Behaviour

Many programs provide a command line interface, such as mail, ftp, and sh. For such programs, the default behaviour of Readline is sufficient. This section describes how to use Readline in the simplest way possible, perhaps to replace calls in your code to gets ().

The function readline prints a prompt and then reads and returns a single line of text from the user. The line which readline () returns is allocated with malloc (); you should free () the line when you are done with it. The declaration in ANSI C is

char *readline (char *prompt);

or, preferably,

#include <readline/readline.h>

So, one might say

char *line = readline ("Enter a line: ");

in order to read a line of text from the user.

The line which is returned has the final newline removed, so only the text of the line remains.

If readline encounters an EOF while reading the line, and the line is empty at that point, then (char *)NULL is returned. Otherwise, the line is ended just as if a newline was typed.

If you want the user to be able to get at the line later, (with <C-p> for example), you must call add_history () to save the line away in a history list of such lines.

add_history (line);

If you use add_history (), you should also #include <readline/history.h> For full details on the GNU History Library, see the associated manual.

It is polite to avoid saving empty lines on the history list, since no one has a burning need to reuse a blank line. Here is a function which usefully replaces the standard gets () library function:

#include <readline/readline.h>
#include <readline/history.h>

/* A static variable for holding the line. */
static char *my_gets_line = (char *)NULL;

/* Read a string, and return a pointer to it.  Returns NULL on EOF. */
char *
my_gets ()
{
  /* If the buffer has already been allocated, return the memory
     to the free pool. */
  if (my_gets_line != (char *)NULL)
    free (my_gets_line);

  /* Get a line from the user. */
  my_gets_line = readline ("");

  /* If the line has any text in it, save it on the history. */
  if (my_get_line && *my_gets_line)
    add_history (my_gets_line);

  return (my_gets_line);
}

The above code gives the user the default behaviour of <TAB> completion: completion on file names. If you do not want readline to complete on filenames, you can change the binding of the <TAB> key with rl_bind_key ().

int rl_bind_key (int key, (int (*)())function);

rl_bind_key () takes 2 arguments; key is the character that you want to bind, and function is the address of the function to run when key is pressed. Binding <TAB> to rl_insert () makes <TAB> just insert itself.

rl_bind_key () returns non-zero if key is not a valid ASCII character code (between 0 and 255).

rl_bind_key ('\t', rl_insert);

2.2 Custom Functions

Readline provides a great many functions for manipulating the text of the line. But it isn’t possible to anticipate the needs of all programs. This section describes the various functions and variables defined in within the Readline library which allow a user program to add customized functionality to Readline.

For the sake of readabilty, we declare a new type of object, called Function. ‘Function’ is a C language function which returns an int. The type declaration for ‘Function’ is:

typedef int Function ();

The reason for declaring this new type is to make it easier to discuss pointers to C functions. Let us say we had a variable called func which was a pointer to a function. Instead of the classic C declaration

int (*)()func;

we have

Function *func;

2.2.1 Naming a Function

The user can dynamically change the bindings of keys while using Readline. This is done by representing the function with a descriptive name. The user is able to type the descriptive name when referring to the function. Thus, in an init file, one might find

Meta-Rubout:	backward-kill-word

This binds <Meta-Rubout> to the function descriptively named backward-kill-word. You, as a programmer, should bind the functions you write to descriptive names as well. Here is how to do that.

Function: rl_add_defun (char *name, Function *function, int key)

Add name to the list of named functions. Make function be the function that gets called. If key is not -1, then bind it to function using rl_bind_key ().

Using this function alone is sufficient for most applications. It is the recommended way to add a few functions to the default functions that Readline has built in already. If you need to do more or different things than adding a function to Readline, you may need to use the underlying functions described below.

2.2.2 Selecting a Keymap

Key bindings take place on a keymap. The keymap is the association between the keys that the user types and the functions that get run. You can make your own keymaps, copy existing keymaps, and tell Readline which keymap to use.

Function: rl_make_bare_keymap ()

Returns a new, empty keymap. The space for the keymap is allocated with malloc (); you should free () it when you are done.

Function: rl_copy_keymap (Keymap map)

Return a new keymap which is a copy of map.

Function: rl_make_keymap ()

Return a new keymap with the printing characters bound to rl_insert, the lowercase Meta characters bound to run their equivalents, and the Meta digits bound to produce numeric arguments.

2.2.3 Binding Keys

You associate keys with functions through the keymap. Here are the functions for doing that.

Function: rl_bind_key (int key, Function *function)

Binds key to function in the currently selected keymap. Returns non-zero in the case of an invalid key.

Function: rl_bind_key_in_map (int key, Function *function, Keymap map)

Bind key to function in map. Returns non-zero in the case of an invalid key.

Function: rl_unbind_key (int key)

Make key do nothing in the currently selected keymap. Returns non-zero in case of error.

Function: rl_unbind_key_in_map (int key, Keymap map)

Make key be bound to the null function in map. Returns non-zero in case of error.

2.2.4 Writing a New Function

In order to write new functions for Readline, you need to know the calling conventions for keyboard invoked functions, and the names of the variables that describe the current state of the line gathered so far.

Variable: char *rl_line_buffer

This is the line gathered so far. You are welcome to modify the contents of this, but see Undoing, below.

Variable: int rl_point

The offset of the current cursor position in rl_line_buffer.

Variable: int rl_end

The number of characters present in rl_line_buffer. When rl_point is at the end of the line, then rl_point and rl_end are equal.

The calling sequence for a command foo looks like

foo (count, key)

where count is the numeric argument (or 1 if defaulted) and key is the key that invoked this function.

It is completely up to the function as to what should be done with the numeric argument; some functions use it as a repeat count, other functions as a flag, and some choose to ignore it. In general, if a function uses the numeric argument as a repeat count, it should be able to do something useful with a negative argument as well as a positive argument. At the very least, it should be aware that it can be passed a negative argument.

2.2.5 Allowing Undoing

Supporting the undo command is a painless thing to do, and makes your function much more useful to the end user. It is certainly easy to try something if you know you can undo it. I could use an undo function for the stock market.

If your function simply inserts text once, or deletes text once, and it calls rl_insert_text () or rl_delete_text () to do it, then undoing is already done for you automatically, and you can safely skip this section.

If you do multiple insertions or multiple deletions, or any combination of these operations, you will want to group them together into one operation. This can be done with rl_begin_undo_group () and rl_end_undo_group ().

Function: rl_begin_undo_group ()

Begins saving undo information in a group construct. The undo information usually comes from calls to rl_insert_text () and rl_delete_text (), but they could be direct calls to rl_add_undo ().

Function: rl_end_undo_group ()

Closes the current undo group started with rl_begin_undo_group (). There should be exactly one call to rl_end_undo_group () for every call to rl_begin_undo_group ().

Finally, if you neither insert nor delete text, but directly modify the existing text (e.g. change its case), you call rl_modifying () once, just before you modify the text. You must supply the indices of the text range that you are going to modify.

Function: rl_modifying (int start, int end)

Tell Readline to save the text between start and end as a single undo unit. It is assumed that subsequent to this call you will modify that range of text in some way.

2.2.6 An Example

Let us say that we are actually going to put an example here.

Typically, a program that reads commands from the user has a way of disambiguating between commands and data. If your program is one of these, then it can provide completion for either commands, or data, or both commands and data. The following sections describe how your program and Readline cooperate to provide this service to end users.

Appendix A Variable Index

Table of Contents

About This Document

This document was generated on March 29, 2022 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on March 29, 2022 using texi2html 5.0.